home *** CD-ROM | disk | FTP | other *** search
/ Die Ultimative Software-P…i Collection 1996 & 1997 / Die Ultimative Software-Pakete CD-ROM fur Atari Collection 1996 & 1997.iso / p / portfoli / pglib / pglib.doc next >
Encoding:
Text File  |  1996-10-30  |  12.6 KB  |  350 lines
  1.  
  2.      PGLIB 1.0 - The Atari Portfolio Graphics Library
  3.      by Don Messerli (Compuserve 72500,1671 or GEnie DMESS)
  4.      Copyright (c)1991 Software Vineyard. 1/9/91
  5.      All Rights Reserved (see "Licensing" at end of docs)
  6.  
  7.      What is it?
  8.      -----------
  9.  
  10.      PGLIB is a 'C' Library of graphics routines for the Atari
  11.      Portfolio.  Included in the archive (.ZIP) are small model
  12.      libraries for Microsoft C 5.0 and above and Borland's Turbo C
  13.      (only tested on Turbo C 2.0).
  14.  
  15.      The library includes basic graphics functions (turn pixels on
  16.      and off, line drawing) as well as functions to handle PGC
  17.      graphics (show, load, and save).  
  18.  
  19.      I hope this library makes it easier for people to write graphic
  20.      applications for the Portfolio and in particular to support
  21.      the PGC graphic file standard.
  22.  
  23.      How do I use it?
  24.      ----------------
  25.  
  26.      Just copy the appropriate library file (PGMS.LIB for Microsoft
  27.      or PGTC.LIB for Turbo C) to the directory specified in your
  28.      LIB environment variable (usually called LIB).  Copy the header
  29.      file (PGLIB.H) to the directory specified in your INCLUDE
  30.      environment variable (usually called INCLUDE).
  31.  
  32.      Make sure you put a line in your program to "include" the
  33.      header file at the beginning of your program:
  34.  
  35.      #include     "pglib.h"
  36.  
  37.      Link the library in with your program.  In Quick C this can
  38.      be specified in a *.mak file.  In Turbo C it is a *.prj file.
  39.      In Microsoft C 5.0, 5.1, or 6.0 this can be done in a make
  40.      file or specified on the LINK command line.
  41.  
  42.      General Usage Hints
  43.      -------------------
  44.  
  45.      You should always call PG_Init before using any other library
  46.      functions.
  47.  
  48.      It would behoove you to put the Portfolio into graphics mode
  49.      before calling any library functions.  This can be accomplished
  50.      painlessly by calling PG_GoGraphic();
  51.  
  52.      Changes will not show up on the screen until you force a screen
  53.      refresh (Portfolio battery saving feature!).  This can be done
  54.      with PG_Refresh() function.  If a library function does it's
  55.      own screen refresh, it is noted in the function reference
  56.      below.
  57.  
  58.      If a library routine says to pass it a far pointer, do it.
  59.      If you pass it a near pointer, problems might not surface
  60.      until runtime.  Follow the rules and you won't get stung.
  61.  
  62.      Function Groupings
  63.      ------------------
  64.  
  65.      Housekeeping            PG_Init, PG_GoGraphic, PG_GoText
  66.      General               PG_ClearScreen, PG_Refresh
  67.      Drawing               PG_Plot, PG_QPlot, PG_GetPixel, PG_Line
  68.      PGC                    PG_Show, PG_Load, PG_Move, PG_Save
  69.  
  70.      Screen Coordinates
  71.      ------------------
  72.  
  73.      The Portfolio screen is 240 pixels wide and 64 pixels high.  PGLIB
  74.      requires coordinates passed as integers starting at (0,0) in the
  75.      upper left corner of the screen.  PGLIB currently does not checking
  76.      to make sure coordinates are in this range.  See diagram below:
  77.  
  78.                                                  239
  79.         0 --------------------------------------->
  80.           |
  81.           |
  82.           |
  83.           |
  84.        63 \/
  85.  
  86.  
  87.      Buffers and the Screen
  88.      ----------------------
  89.  
  90.      The PGC functions in PGLIB can read to, write to disk from, and move
  91.      images between buffers and the screen.  If you specify the constant
  92.      SCREEN as a parameter to PG_Read, PG_Save or PG_Move instead of a
  93.      far pointer to a buffer, PGLIB will create a far pointer to the
  94.      screen for you and use that as the buffer.  (This is a good place
  95.      to remind you to be sure to use far pointers to buffers.)  This
  96.      buffer flexibility allows you to read in PGC images without displaying
  97.      them and hold multiple PGC images in memory at one time.
  98.  
  99.      The following command will copy an image from a memory buffer to
  100.      the screen:
  101.  
  102.      result = PG_Move(SCREEN, (char far *)mybuffer);
  103.  
  104.      Buffers can be dynamically allocated or static char arrays.  They
  105.      must be 1920 bytes in size.
  106.  
  107.      Any time you specify SCREEN as the target of a PGC function, a
  108.      screen refresh is also performed.
  109.  
  110.  
  111.      Function Reference (alphabetical)
  112.      ------------------
  113.  
  114.      void PG_ClearScreen(void)
  115.  
  116.           Parameters: None
  117.           Returns: Nothing
  118.  
  119.           Clears the screen in Graphics or Text mode.
  120.  
  121.  
  122.      int     PG_GetPixel(int x, int y)
  123.      
  124.           Parameters:      int x - the x (horizontal) pixel coordinate
  125.                          int y - the y (vertical) pixel coordinate
  126.           Returns: 1 if on, 0 if off
  127.  
  128.           This function is used to determine whether a pixel on the
  129.           screen is on (BLACK) or off (WHITE).  The constants BLACK
  130.           and WHITE can be used.  See "Coordinates" section above.
  131.           
  132.           I do not use the BIOS to read the pixel because it did not
  133.           work on earlier versions of the Portfolio ROMs.
  134.  
  135.      void     PG_GoGraphic(void)
  136.           
  137.           Parameters: None
  138.           Returns: Nothing
  139.  
  140.           Puts the Portfolio into Graphics mode and clears the screen.
  141.           No refresh required.
  142.  
  143.  
  144.      void     PG_GoText(void)
  145.  
  146.           Parameters: None
  147.           Returns: Nothing
  148.  
  149.           Puts the Portfolio into Text mode and clears the screen.
  150.           No refresh required.
  151.  
  152.  
  153.      int     PG_Init(void)
  154.  
  155.           Parameters: None
  156.           Returns: 1 if successful, 0 if not a Portfolio
  157.  
  158.           Checks to make sure program is running on a Portfolio and
  159.           initializes the Portfolio int61 routines which are used
  160.           by some library routines.     
  161.      
  162.  
  163.      void     PG_Line(int x1, int y1, int x2, int y2, int color)
  164.  
  165.           Parameters:     int x1 - upper left horiz. coordinate
  166.                          int y1 - upper left vertical coordinate
  167.                          int x2 - lower right horiz. coordinate
  168.                          int y2 - lower right vertical coordinate
  169.                          int color - BLACK or WHITE
  170.           Returns: Nothing
  171.  
  172.           Draws a line from (x1,y1) to (x2,y2) in either BLACK or
  173.           WHITE.  No refresh required. See "Coordinates" section
  174.           above.
  175.  
  176.  
  177.      int     PG_Read(char *filename, char far *buffer)
  178.  
  179.           Parameters:     char *filename - pointer to name of PGC file
  180.                          char *far buffer - buffer to receive image
  181.           Returns: 0 if successful, error code if not
  182.  
  183.           This routine reads a PGC file from disk into the specified
  184.           buffer or to the screen.  See "Buffers" section above.  If
  185.           reading to the screen, a screen refresh is done.
  186.  
  187.           Error Codes:
  188.                BADOPEN - error opening file
  189.                NOTPGC  - not a PGC file
  190.                
  191.  
  192.      void     PG_Move(char far *destbuffer, char far *srcbuffer)
  193.  
  194.           Parameters:     char far *destbuffer - pointer to destination
  195.                                                 buffer.
  196.                          char far *frombuffer - pointer to source
  197.                                                 buffer.
  198.           Returns: Nothing
  199.  
  200.           Copies a PGC image from one buffer to another.  Either of
  201.           the buffers can be the screen. See "Buffers"     section above.
  202.  
  203.  
  204.      void     PG_Plot(int x, int y, int color)
  205.      void     PG_QPlot(int x, int y, int color)
  206.  
  207.           Parameters:      int x - the x (horizontal) pixel coordinate
  208.                          int y - the y (vertical) pixel coordinate
  209.           Returns: Nothing
  210.  
  211.           This function is used to turn pixels on and off.
  212.           The constants BLACK and WHITE can be used.
  213.           See "Coordinates" section above. No refresh required.
  214.  
  215.           The PG_QPlot routine write directly to the screen.  It
  216.           is not any faster than the BIOS because PGLIB is currently
  217.           written in C.  The "Q" is for quiet, not quick. PG_QPlot
  218.           does not refresh the screen; therefore, you can plot
  219.           a bunch of pixels and then call PG_Refresh at the end.
  220.  
  221.           
  222.      void     PG_Refresh(void)
  223.  
  224.           Parameters: None
  225.           Returns: Nothing
  226.  
  227.           Forces a screen refresh so changes can be seen.
  228.  
  229.  
  230.      int     PG_Show(char *filename)
  231.  
  232.           Parameters:      char *filename - pointer to name of PGC file          
  233.           Returns: 0 if successful, error code if not 
  234.      
  235.           Reads a PGC file from disk directly to the screen and
  236.           then forces a screen refresh.
  237.  
  238.           Error Codes:
  239.                BADOPEN     - error opening file
  240.                NOTPGC     - not a PGC file
  241.  
  242.  
  243.      int     PG_Save(char *filename, char far *buffer)
  244.           
  245.           Parameters:     char *filename - pointer to name of PGC file
  246.                          char far *buffer - pointer to buffer holding image
  247.           Returns: 0 if successful, error code if not
  248.  
  249.           Save the contents of a buffer or the screen to a PGC file.  See 
  250.           "Buffers" section above.  
  251.  
  252.           Error Codes:
  253.                BADOPEN     - error opening file
  254.                BADWRITE     - error writing file
  255.  
  256.  
  257.      Sample Programs
  258.      ---------------
  259.  
  260.      I have only included one sample program with this release of
  261.      PGLIB.  It is called pgsample.c.  It should compile under small
  262.      model with either Microsoft or Turbo C.  It uses all the PGLIB
  263.      functions except PG_GETPIXEL.  The strange screen wipe look is
  264.      just the way the Portfolio does a screen refresh.
  265.  
  266.      Future Enhancements
  267.      -------------------
  268.  
  269.      PGLIB is written in C with some in-line assembler.  I will be
  270.      converting more of the functions to in-line assembler and ultimately
  271.      pure assembly language.  This should make it a little smaller and
  272.      faster.  Don't expect miracles.
  273.  
  274.      I also plan to add routines to do text output onto graphics screens,
  275.      something that isn't supported by the Portfolio's BIOS.
  276.  
  277.      If you have any suggestions of features to add to PGLIB (within
  278.      reason), please contact me.
  279.  
  280.      Revision History
  281.      ----------------
  282.  
  283.      Version 1.0 - 1/9/91
  284.           Initial Release
  285.  
  286.      Licensing
  287.      ---------
  288.  
  289.      PGLIB contains an embedded copyright message.  You are not allowed
  290.      under any circumstances to remove or alter it in any way.  If you
  291.      use LZEXE to compress your programs, I understand that the copyright
  292.      message is not readable in the executable file on disk.  That is
  293.      an acceptable situation.  However, if the file is uncompressed, the
  294.      copyright message must be intact.
  295.  
  296.      I have defined three types of applications.  Check the paragraph
  297.      below for further licensing restrictions based on the type of
  298.      application you are creating:
  299.  
  300.      Public Domain or Freeware
  301.  
  302.      [This is a program you donate to the public domain and ask for no
  303.      money in return.  You may still retain rights to the program
  304.      and restrict it's sale.]
  305.  
  306.      I place no further licensing restrictions on Public Domain programs
  307.      created using PGLIB.
  308.  
  309.      Shareware
  310.  
  311.      [This is a program that contains a request for a donation of some
  312.      sort.  Sometimes promising added value if one registers (i.e. a
  313.      printed manual).]
  314.  
  315.      If you create a Shareware program using PGLIB,  you must send a
  316.      copy (electronically or by mail) to Software Vineyard and consider
  317.      Don Messerli a "registered user" of your program granting me all
  318.      rights that entitles me to (if any).  You must also mention Software
  319.      Vineyard in your program's documentation with the a message
  320.      similar to the following:
  321.  
  322.      "PGC Graphics Routines are Copyright (c)1991 Software Vineyard."
  323.  
  324.      Commercial Software
  325.  
  326.      [This is a program that you require payment for.]
  327.  
  328.      If you create a Commercial program using PGLIB, you must fulfill
  329.      all of the requirements listed above for Shareware (including
  330.      sending a copy to Software Vineyard) and pay a one time fee
  331.      of $25 (US).
  332.  
  333.      I don't think these terms are unfair.  If you do, we can discuss
  334.      it.  Or you can write your own routines and not use PGLIB.
  335.  
  336.      How to Contact Don Messerli (Software Vineyard)
  337.      -----------------------------------------------
  338.  
  339.      Compuserve 72500,1671     Mail:     Software Vineyard
  340.      GEnie      DMESS                    1394 Amherst St. #17
  341.                                         Buffalo, NY  14216
  342.  
  343.      A Final Word (for now)
  344.      ----------------------
  345.  
  346.      If you like PGLIB, let me know.  Feedback is the only way I can
  347.      improve my programs.  Most importantly,  have fun!
  348.                                                             DM
  349.  
  350.